新增微信公众号统计功能

Description

新增完整的微信公众号文章统计分析功能,支持每日数据采集、多维度趋势分析和文章排行榜展示。该功能为内容运营团队提供数据驱动的决策支持,帮助评估文章表现、优化内容策略。

核心亮点:

• 📊 多维度统计: 阅读量、点赞、分享、评论、收藏、粉丝增长等 10+ 指标
• 📈 灵活趋势分析: 支持日/周/月/季/半年/年 6 种时间周期,可按文章分类筛选
• 🏆 文章排行榜: 基于最新数据的 Top N 文章排名
• 🔄 智能聚合: 预聚合表设计,支持大数据量快速查询
• 🏷️ 分类管理: 版本发布/技术文章/活动三大分类体系

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🔧 Configuration change
• 🎨 Code refactoring (no functional changes)
• ⚡️ Performance improvement
• ✅ Test addition or update

Changes Made

数据模型层 (Models)

• ✅ 新增 WechatArticleStat 模型 - 文章每日统计快照表
  • 支持 10+ 互动指标 (阅读量、点赞、分享、评论、收藏等)
  • 文章分类字段 (release/technical/activity)
  • 社区级数据隔离 (community_id)
  • 唯一约束确保每文章每天一条记录
• ✅ 新增 WechatStatsAggregate 模型 - 多维度聚合统计表
  • 支持 6 种时间周期 (daily/weekly/monthly/quarterly/semi_annual/annual)
  • 按分类预聚合,加速查询
  • 自动计算平均阅读量等衍生指标

业务逻辑层 (Services)

• ✅ 创建 WechatStatsService 服务类 (app/services/wechat_stats.py)
  • create_daily_stat() / batch_create_daily_stats() - 每日数据录入
  • get_overview() - 统计概览 (总量、分类汇总、Top 10)
  • get_trend() - 趋势数据 (可选周期/分类/日期范围)
  • get_article_ranking() - 文章排行榜
  • rebuild_aggregates() - 聚合数据重建
  • update_article_category() - 批量更新文章分类
  • 实现智能回退机制:聚合表无数据时从原始表实时计算

API 路由层 (Routes)

• ✅ 新增 app/api/wechat_stats.py 路由模块
  • GET /api/wechat-stats/overview - 获取统计概览
  • GET /api/wechat-stats/trend - 获取趋势图表数据 (支持 6 种周期)
  • GET /api/wechat-stats/ranking - 获取文章排行榜 (可按分类筛选)
  • GET /api/wechat-stats/articles/{publish_record_id}/daily - 获取单篇文章每日统计
  • PUT /api/wechat-stats/articles/{publish_record_id}/category - 更新文章分类
  • POST /api/wechat-stats/daily - 录入单条每日统计
  • POST /api/wechat-stats/daily/batch - 批量录入每日统计
  • POST /api/wechat-stats/aggregates/rebuild - 重建聚合数据
• ✅ 在 app/main.py 中注册路由

Schema 层 (Pydantic Models)

• ✅ 创建 app/schemas/wechat_stats.py
  • WechatArticleStatOut - 每日统计输出
  • WechatDailyStatCreate / WechatDailyStatBatchCreate - 统计数据录入
  • WechatStatsAggregateOut - 聚合统计输出
  • TrendResponse / TrendDataPoint - 趋势图表数据结构
  • WechatStatsOverview / CategorySummary - 概览数据结构
  • ArticleRankItem - 排行榜数据结构
  • ArticleCategoryUpdate - 分类更新请求

数据库变更

• ✅ Alembic 迁移脚本: 008_add_wechat_stats.py
  • 创建 wechat_article_stats 表 (12 个指标字段)
  • 创建 wechat_stats_aggregates 表 (聚合预计算)
  • 添加索引优化查询 (publish_record_id, stat_date, article_category, community_id)
  • 添加复合索引 (category + date, community + date)
  • 唯一约束防止重复数据

新增表结构

wechat_article_stats (文章每日统计表)

索引:

• ix_wechat_article_stats_publish_record_id
• ix_wechat_article_stats_stat_date
• ix_wechat_article_stats_article_category
• ix_wechat_article_stats_community_id
• ix_wechat_stats_category_date (复合)
• ix_wechat_stats_community_date (复合)

约束: uq_article_stat_date (publish_record_id + stat_date)

wechat_stats_aggregates (聚合统计表)

索引:

• ix_wechat_stats_aggregates_community_id
• ix_wechat_stats_aggregates_period_type
• ix_wechat_stats_aggregates_period_start
• ix_aggregate_period (复合: community_id + period_type + period_start)

约束: uq_stats_aggregate (community_id + period_type + period_start + article_category)

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Manual testing completed
• Test script provided

Test Instructions

# 1. 进入后端目录
cd backend

# 2. 运行数据库迁移
alembic upgrade head

# 3. 启动开发服务器
make dev-backend

# 4. 访问 API 文档测试端点
# http://localhost:8000/docs#/WeChat%20Statistics

# 5. 测试场景示例

# 5.1 录入每日统计 (POST /api/wechat-stats/daily)
curl -X POST "http://localhost:8000/api/wechat-stats/daily" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "publish_record_id": 1,
    "article_category": "technical",
    "stat_date": "2026-02-10",
    "read_count": 1500,
    "like_count": 50,
    "share_count": 20
  }'

# 5.2 获取统计概览 (GET /api/wechat-stats/overview)
curl -X GET "http://localhost:8000/api/wechat-stats/overview" \
  -H "Authorization: Bearer <token>"

# 5.3 获取趋势数据 (GET /api/wechat-stats/trend)
curl -X GET "http://localhost:8000/api/wechat-stats/trend?period_type=weekly&category=technical" \
  -H "Authorization: Bearer <token>"

# 5.4 获取文章排行榜 (GET /api/wechat-stats/ranking)
curl -X GET "http://localhost:8000/api/wechat-stats/ranking?limit=20" \
  -H "Authorization: Bearer <token>"

# 5.5 更新文章分类 (PUT /api/wechat-stats/articles/{id}/category)
curl -X PUT "http://localhost:8000/api/wechat-stats/articles/1/category" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"article_category": "release"}'

# 5.6 重建聚合数据 (POST /api/wechat-stats/aggregates/rebuild)
curl -X POST "http://localhost:8000/api/wechat-stats/aggregates/rebuild?period_type=monthly" \
  -H "Authorization: Bearer <token>"

# 6. 运行单元测试
pytest tests/test_wechat_stats_api.py -v

测试覆盖场景

• ✅ 每日统计 CRUD (单条/批量录入、查询、更新)
• ✅ 文章分类管理 (创建时指定、批量更新)
• ✅ 统计概览数据正确性 (总量、分类汇总、Top 10)
• ✅ 趋势数据 6 种周期计算 (daily/weekly/monthly/quarterly/semi_annual/annual)
• ✅ 趋势数据按分类筛选 (release/technical/activity/全部)
• ✅ 文章排行榜排序正确性
• ✅ 聚合数据重建功能
• ✅ 日期范围筛选
• ✅ 社区数据隔离
• ✅ 权限验证 (需登录)